<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>numpy.random.multinomial &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../../../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../../../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../../../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../../../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../../_static/language_data.js"></script>
    <script type="text/javascript" src="../../../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../../../about.html" >
    <link rel="index" title="Index" href="../../../genindex.html" >
    <link rel="search" title="Search" href="../../../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../../../index.html" >
    <link rel="up" title="Legacy Random Generation" href="../legacy.html" >
    <link rel="next" title="numpy.random.multivariate_normal" href="numpy.random.multivariate_normal.html" >
    <link rel="prev" title="numpy.random.logseries" href="numpy.random.logseries.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../../../index.html">
      <img border=0 alt="NumPy" src="../../../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../../../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="../../index.html" >NumPy Reference</a></li>
          <li class="active"><a href="../../routines.html" >Routines</a></li>
          <li class="active"><a href="../index.html" >Random sampling (<code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy.random</span></code>)</a></li>
          <li class="active"><a href="../legacy.html" accesskey="U">Legacy Random Generation</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../../../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="numpy.random.multivariate_normal.html" title="numpy.random.multivariate_normal"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="numpy.random.logseries.html" title="numpy.random.logseries"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h4>Previous topic</h4>
  <p class="topless"><a href="numpy.random.logseries.html"
                        title="previous chapter">numpy.random.logseries</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="numpy.random.multivariate_normal.html"
                        title="next chapter">numpy.random.multivariate_normal</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../../../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="numpy-random-multinomial">
<h1>numpy.random.multinomial<a class="headerlink" href="#numpy-random-multinomial" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="numpy.random.multinomial">
<code class="sig-prename descclassname">numpy.random.</code><code class="sig-name descname">multinomial</code><span class="sig-paren">(</span><em class="sig-param">n</em>, <em class="sig-param">pvals</em>, <em class="sig-param">size=None</em><span class="sig-paren">)</span><a class="headerlink" href="#numpy.random.multinomial" title="Permalink to this definition">¶</a></dt>
<dd><p>Draw samples from a multinomial distribution.</p>
<p>The multinomial distribution is a multivariate generalization of the
binomial distribution.  Take an experiment with one of <code class="docutils literal notranslate"><span class="pre">p</span></code>
possible outcomes.  An example of such an experiment is throwing a dice,
where the outcome can be 1 through 6.  Each sample drawn from the
distribution represents <em class="xref py py-obj">n</em> such experiments.  Its values,
<code class="docutils literal notranslate"><span class="pre">X_i</span> <span class="pre">=</span> <span class="pre">[X_0,</span> <span class="pre">X_1,</span> <span class="pre">...,</span> <span class="pre">X_p]</span></code>, represent the number of times the
outcome was <code class="docutils literal notranslate"><span class="pre">i</span></code>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>New code should use the <code class="docutils literal notranslate"><span class="pre">multinomial</span></code> method of a <code class="docutils literal notranslate"><span class="pre">default_rng()</span></code>
instance instead; see <em class="xref py py-obj">random-quick-start</em>.</p>
</div>
<dl class="field-list">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>n</strong><span class="classifier">int</span></dt><dd><p>Number of experiments.</p>
</dd>
<dt><strong>pvals</strong><span class="classifier">sequence of floats, length p</span></dt><dd><p>Probabilities of each of the <code class="docutils literal notranslate"><span class="pre">p</span></code> different outcomes.  These
must sum to 1 (however, the last element is always assumed to
account for the remaining probability, as long as
<code class="docutils literal notranslate"><span class="pre">sum(pvals[:-1])</span> <span class="pre">&lt;=</span> <span class="pre">1)</span></code>.</p>
</dd>
<dt><strong>size</strong><span class="classifier">int or tuple of ints, optional</span></dt><dd><p>Output shape.  If the given shape is, e.g., <code class="docutils literal notranslate"><span class="pre">(m,</span> <span class="pre">n,</span> <span class="pre">k)</span></code>, then
<code class="docutils literal notranslate"><span class="pre">m</span> <span class="pre">*</span> <span class="pre">n</span> <span class="pre">*</span> <span class="pre">k</span></code> samples are drawn.  Default is None, in which case a
single value is returned.</p>
</dd>
</dl>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><dl>
<dt><strong>out</strong><span class="classifier">ndarray</span></dt><dd><p>The drawn samples, of shape <em>size</em>, if that was provided.  If not,
the shape is <code class="docutils literal notranslate"><span class="pre">(N,)</span></code>.</p>
<p>In other words, each entry <code class="docutils literal notranslate"><span class="pre">out[i,j,...,:]</span></code> is an N-dimensional
value drawn from the distribution.</p>
</dd>
</dl>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<dl class="simple">
<dt><a class="reference internal" href="numpy.random.Generator.multinomial.html#numpy.random.Generator.multinomial" title="numpy.random.Generator.multinomial"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Generator.multinomial</span></code></a></dt><dd><p>which should be used for new code.</p>
</dd>
</dl>
</div>
<p class="rubric">Examples</p>
<p>Throw a dice 20 times:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">multinomial</span><span class="p">(</span><span class="mi">20</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="o">/</span><span class="mf">6.</span><span class="p">]</span><span class="o">*</span><span class="mi">6</span><span class="p">,</span> <span class="n">size</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="go">array([[4, 1, 7, 5, 2, 1]]) # random</span>
</pre></div>
</div>
<p>It landed 4 times on 1, once on 2, etc.</p>
<p>Now, throw the dice 20 times, and 20 times again:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">multinomial</span><span class="p">(</span><span class="mi">20</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="o">/</span><span class="mf">6.</span><span class="p">]</span><span class="o">*</span><span class="mi">6</span><span class="p">,</span> <span class="n">size</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="go">array([[3, 4, 3, 3, 4, 3], # random</span>
<span class="go">       [2, 4, 3, 4, 0, 7]])</span>
</pre></div>
</div>
<p>For the first run, we threw 3 times 1, 4 times 2, etc.  For the second,
we threw 2 times 1, 4 times 2, etc.</p>
<p>A loaded die is more likely to land on number 6:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">multinomial</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="o">/</span><span class="mf">7.</span><span class="p">]</span><span class="o">*</span><span class="mi">5</span> <span class="o">+</span> <span class="p">[</span><span class="mi">2</span><span class="o">/</span><span class="mf">7.</span><span class="p">])</span>
<span class="go">array([11, 16, 14, 17, 16, 26]) # random</span>
</pre></div>
</div>
<p>The probability inputs should be normalized. As an implementation
detail, the value of the last entry is ignored and assumed to take
up any leftover probability mass, but this should not be relied on.
A biased coin which has twice as much weight on one side as on the
other should be sampled like so:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">multinomial</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="p">[</span><span class="mf">1.0</span> <span class="o">/</span> <span class="mi">3</span><span class="p">,</span> <span class="mf">2.0</span> <span class="o">/</span> <span class="mi">3</span><span class="p">])</span>  <span class="c1"># RIGHT</span>
<span class="go">array([38, 62]) # random</span>
</pre></div>
</div>
<p>not like:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">multinomial</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="p">[</span><span class="mf">1.0</span><span class="p">,</span> <span class="mf">2.0</span><span class="p">])</span>  <span class="c1"># WRONG</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="gr">ValueError</span>: <span class="n">pvals &lt; 0, pvals &gt; 1 or pvals contains NaNs</span>
</pre></div>
</div>
</dd></dl>

</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>